DIY Exercise 3-1: Create an API specification with RAML

Time estimate: 1 hour

Objectives

In this exercise, you create an API specification using RAML. You will:

·       Appropriately specify GET and POST methods.

·       Appropriately define URI parameters, query parameters, and headers.

·       Restrict possible values using an enumeration.

Scenario

Your company needs to expose a customer accounts database as a System API for the rest of the organization. The first step is to create the RAML specification and post it to your company’s private Anypoint Exchange so all stakeholders can review and provide feedback. This RAML specification needs to separate out data type definitions from the main API RAML file into separate reusable RAML files.

Create the API specification

In Design Center, create a RAML specification called Accounts API with the following requirements:

·       The API has a resource called accounts.

·       All client requests must include the required header Requester-ID. This header helps identify the person in the organization making account requests.

·       The /accounts resource has a GET method with a required queryParameter named type, where type must be either personal or business. The type query parameter is used to return records that match that account's type.

·       The GET method for the /accounts resource has two optional string queryParameters named name and country. The name query parameter value is used to filter and return all account records for a particular account owner. The country query parameter value is used to filter and return records matching the account owner's country of residence.

·       The GET method’s response data is an array of Account objects. To represent the response data, define and use an Account data type that contain the following fields: id, firstName, lastName, address, postal, country, miles, creationDate, and type. The creationDate field is of type datetime and miles is of type integer.

·       The API defines and uses a data type for the Account object that is stored in a separate RAML file.

·       The Account data type definition has a corresponding example that is included in the main API RAML file or in the Account data type RAML file.

·       The /accounts resource has a POST method that accepts an array of Account objects (with no id and no creationDate field) in JSON format and returns a JSON message: {"message": "Account created (but not really)"}. This Account object is represented as a new data type that does not have id or creationDate fields, makes the type field required, and has a corresponding example.

·       Each method should have a description.

·       Each method should have a custom 400 error status message example in JSON format.

Publish the API to Anypoint Exchange

Publish the API to Anypoint Exchange and then test the mocked endpoint using the API Console and create a public portal for the API.

Verify your solution

Load the solution /files/module03/accounts-mod03-api-solution.zip (in the MUFundamentals4.x DIY Files zip that you can download from the Course Resources) and compare your solution.